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Chapter 1 


DNET HTTP(S) Foundation API 


1.1 References 


[1] Software Architecture Document, Version 1.1 Revision 1.4, LiMo Foundation, 11 September 2007 


1.2 Overview 


LiMo HTTP(S) API. This specification describes the LiMo HTTP API specification. 
The HTTP API that this specification defines is that of the interface indicated as yellow in the figure below. 


TCP / WTCP 
IP 


Figure 1.1: Network component structure 


HTTPLib is designed with the basic concept as below. 
HTTP handle : HTTP instance handle. The calling application can have one or more HTTP handles. 
Session : Connection unit for each destination. 


Transaction : An unit paired of one request and its response under the session. The response does not have 


2 DNET HTTP(S) Foundation API 


to be one. 


*TR stands br Transaction nthisFigue. 


Figure 1.2: Basic concept 


Note: 


An HTTP handle, session handle and transaction handle are unique in a process. 
A session handle is linked to an HTTP handle with NetHttpNewSession. 
A transaction handle is linked to a session handle with NetHttpRequest. 


1.3 Industry Standard 


IETF RFC 2616, "Hypertext Transfer Protocol- HTTP/1.1", http: //www.w3.org/Protocols/rfc2616/rfc2616.] 


1.4 External API Documents 


None 


1.5 Plug-in Extension Point Interface 


None 


1.6 Other Interfaces 


None 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


1.7 Other Notes 3 


1.7 Other Notes 


e Illustrative Call Sequence Charts. 


e Important Supplementary Information. 


Note: 


HTTP Lib is designed to utilize OpenSSL for HTTPS in LiMo Platform Release 1. An OEM 
could use other solution, or offer additional APIs but it is up to OEM to implement. See 
http://www.openssl.org/. 


Warning: 


This HTTP API document contains descriptions about chunk transmission support. But this feature 
will not be supported in the LiMo Foundation Platform Release 1. 

HTTPLib does not support "Content-Type: multipart" that is not accompanied by any one of "content- 
length," "Transfer-Encoding: chunked" or "Connection: Close." If this happens, the transaction and 
connection are terminated. In this case, the event NET_.HTTP_EV_ RECEIVED HEADER will not 
be reported. 
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Chapter 2 


Data Structure Index 


2.1 Data Structures 


Here are the data structures with brief descriptions: 


INSP UDEVEO og acd ack als Rae a dee See Goat ee ee ee oe ee Ee eS 
Nethitipevintstonnetied.. = 2.3. 2 Sa a 2 nn EOS RES ERS GEE SEG ES 
NetHitpEvintoContentBufRegquired ....:+ . aus Se SER Se eben 
NetHttpEvinfoDisconnected < e ca ecri eR ERS EE ei DE Era eee eH 
NethttpEvintoHeaderBuiRequired o... ks 
NetHttpEvinfoNewBufRequired ... 2... sec 0... nenn 
NethttpEvinfoReceivedComtent -o sc ss ccoa Su ee e nn 
NetHitpEvinfoRscewedHeader < eee eR ds ee 
NELHIEtBENINISR ec Pins Content rca ern A a es 
NetHttpEvintoRecevingHealer oo ccs ei a mw Ken rin a nn 
NeiRIpPE RIESE ic ae en a ne oS 
NerHitpErintesshlertErer plo arten Er ae en 
Nepas lese 2 eat SER oH nw Se Oe Ch eae na 
NEIHEBEFINDSSs I Hlabindi. esos por ek Sana E ee ee eS 
Nethitipevintassllishiait > ig 2.2. aw eS he eee Se abt beta ee Ae ati ee 
NethttpEvintoliansactionAbort ...o:¿. Se EA Re RS 
NetHttpEvinfoTransactionComplete .............. 0000002 eee ee eee 
NEHEDSSICH Para o oe kG Wek hg Rw E ee ee E Se A 


Data Structure Index 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


Chapter 3 


File Index 


3.1 File List 


Here is a list of all documented files with brief descriptions: 


ComponentOverview.h (Component Programming Interface Overview Header Template for 


Doxysen) 222864 a bad Caw Oe Rede BES Oe BS eS ES 2 DEE ES 35 
httpMSCs.h (Illustrative HTTP API Call Sequence Charts)... . ooa 36 
httpSuppInfo.h (Open SSL related supplementary information). ................. 54 


nethttpif.h (LiMo HTTP Library API Header) ....... Comm nn 57 


File Index 
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Chapter 4 


Data Structure Documentation 


4.1 NetHttpEvent Struct Reference 


#include <nethttpif.h> 


4.1.1 Detailed Description 


Event Information Structs 


Data Fields 


e NetHttpEventld event_id 


e union { 

NetHttpEvinfoConnected connected 
NetHttpEvinfoDisconnected disconnected 
NetHttpEvinfoSslHsStart ssl_hs_start 
NetHttpEvinfoSslHsEnd ssl_hs_end 
NetHttpEvinfoSslCertError ssl_cert_error 
NetHttpEvinfoSslClose ssl_close 
NetHttpEvinfoHeaderBufRequired header_buf_required 
NetHttpEvinfoContentBufRequired content_buf_required 
NetHttpEvinfoSent sent 

NetHttpEvinfoReceivingHeader receiving header 
NetHttpEvinfoReceivedHeader received_header 
NetHttpEvinfoReceivingContent receiving content 
NetHttpEvinfoReceivedContent received_content 
NetHttpEvinfoTransactionComplete transaction_complete 
NetHttpEvinfoTransactionAbort transaction_abort 
NetHttpEvinfoNewBufRequired new_buf_required 

} event_info 
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4.1.2 Field Documentation 
4.1.2.1 NetHttpEventId NetHttpEvent::event_id 


Event ID 


4.1.2.2 NetHttpEvinfoConnected NetHttpEvent::connected 


NET_HTTP_EV_CONNECTED 


4.1.2.3 NetHttpEvinfoDisconnected NetHttpEvent::disconnected 


NET_HTTP_EV_DISCONNECTED 


4.1.2.4 NetHttpEvinfoSsIHsStart NetHttpEvent::ssl_hs_start 


NET_HTTP_EV_SSL_HS_START 


4.1.2.5 NetHttpEvinfoSsIHsEnd NetHttpEvent::ssl_hs_end 


NET_HTTP_EV_SSL_HS_END 


4.1.2.6 NetHttpEvinfoSsICertError NetHttpEvent::ssl_cert_error 


NET_HTTP_EV_SSL_CERT_ERROR 


4.1.2.7 NetHttpEvinfoSslClose NetHttpEvent::ssl_close 


NET_HTTP_EV_SSL_CLOSE 


4.1.2.8 NetHttpEvinfoHeaderBufRequired NetHttpEvent::header_buf_required 


NET_HTTP_EV_HEADER_BUF_REQUIRED 


4.1.2.9 NetHttpEvinfoContentBufRequired NetHttpEvent::content_buf_required 


NET_HTTP_EV_CONTENT_BUF_REQUIRED 


4.1.2.10 NetHttpEvinfoSent NetHttpEvent::sent 


NET_HTTP_EV_SENT 


4.1.2.11 NetHttpEvinfoReceivingHeader NetHttpEvent::receiving_header 


NET_HTTP_EV_RECEIVING_HEADER 
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4.1.2.12 NetHttpEvinfoReceivedHeader NetHttpEvent::received_header 


NET_HTTP_EV_RECEIVED_HEADER 


4.1.2.13 NetHttpEvinfoReceivingContent NetHttpEvent::receiving_content 


NET_HTTP_EV_RECEIVING_CONTENT 


4.1.2.14 NetHttpEvinfoReceivedContent NetHttpEvent::received_content 


NET_HTTP_EV_RECEIVED_CONTENT 


4.1.2.15 NetHttpEvinfoTransactionComplete NetHttpEvent::transaction_complete 


NET_HTTP_EV_TRANSACTION_COMPLETE 


4.1.2.16 NetHttpEvinfoTransactionAbort NetHttpEvent::transaction_abort 


NET_HTTP_EV_TRANSACTION_ABORT 


4.1.2.17 NetHttpEvinfoNewBufRequired NetHttpEvent::new_buf_required 


NET_HTTP_EV_NEW_BUF_REQUIRED 


4.1.2.18 union { ... } NetHttpEvent::event_info 


Event Information 


The documentation for this struct was generated from the following file: 


e nethttpif.h 
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4.2 NetHttpEvinfoConnected Struct Reference 


#include <nethttpif.h> 


4.2.1 Detailed Description 


Notify the connection has successfully been established (NET_HTTP_EV_CONNECTED). 


Data Fields 


e NetHttpSesHandle ses 
e void * ses_user 


4.2.2 Field Documentation 
4.2.2.1 NetHttpSesHandle NetHttpEvinfoConnected::ses 


[1n] Session handle of the target session 


4.2.2.2 void» NetHttpEvinfoComnected::ses_user 


[in] User pointer for the session 


The documentation for this struct was generated from the following file: 


e nethttpif.h 
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4.3 NetHttpEvinfoContentBufRequired Struct Reference 


#include <nethttpif.h> 


4.3.1 Detailed Description 


Notify the receive body buffer is short (NET_HTTP_EV_CONTENT_BUF_REQUIRED). 


The calling application should allocate a buffer for receiving the body part and return the pointer of the 
beginning of the memory area which is newly allocated. There is no need to copy the body that is not 
completely received in this region. 


Note: 


If the calling application cannot allocate enough memory, it should return without modifying content_- 
buf and content_bufsize. In this case, it should notify NET_HTTP_EV_TRANSACTION_ABORT 
(NET_HTTP_RC_OUT_OF_MEMORY) to its transaction. 

The min_required parameter indicates the receive buffer size that will be required at a minimum. This 
value is the smallest size that may be required and it is probable that a buffer of greater size than that 
will be necessary. HTTPLib designer recommends that the application allocates the biggest buffer as 
possible to avoid performance degradation due to repeated buffer allocations. HTTPLib allows the 
application to prepare a buffer of smaller size than indicated by ’min_required’ parameter. In this 
case, an extra NET_HTTP_EV_CONTENT_BUF_REQUIRED will be notified to fulfill the lack of 
the necessary buffer. The ’min_required’ parameter may be utilised for receiving data chunk by chunk. 
The value of ’min_required’ parameter may change according to the value of ’content_len’ reported 
via NET_HTTP_EV_RECEIVED_HEADER. 


e content_len is greater than zero (0): content_len value minus the length already received (if 
Content-Length is 1000 and the application has received 500 bytes, ’min_required’ is 500.) 


e content_len was NET_HTTP_CONTENT_LEN_UNKNOWN: Length received and pending on 
the socket at this moment 


e content_len is NET_HTTP_CONTENT_LEN_CHUNK: Chunk size minus the length already 
received for this chunk (if the current chunk size is 1000 bytes and 500 bytes are already passed, 
*min_required” is 500) 


Warning: 
If the min_required size indication feature is not implemented in HTTPLib, the ’min_required’ param- 


eter is always zero(0). 


Data Fields 


NetHttpTrHandle tr 
void * tr_user 

void * content_buf 
int content_bufsize 
int min_required 


4.3.2 Field Documentation 
4.3.2.1 NetHttpTrHandle NetHttpEvinfoContentBufRequired::tr 


[in] Transaction handle 
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4.3.2.2 void» NetHttpEvinfoContentBufRequired::tr_user 


[in] User pointer for the transaction 


4.3.2.3 void+ NetHttpEvinfoContentBufRequired::content_buf 


[in] NULL [out] Receive buffer for the next part of the body 


4.3.2.4 int NetHttpEvinfoContentBufRequired::content_bufsize 


[in] 0 [out] Size of the buffer 


4.3.2.5 int NetHttpEvinfoContentBufRequired::min_required 


[in] Minimum-required buffer size 


The documentation for this struct was generated from the following file: 


e nethttpif.h 
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4.4 NetHttpEvinfoDisconnected Struct Reference 


#include <nethttpif.h> 


4.4.1 Detailed Description 


Notify the connection has been disconnected (NET_HTTP_EV_DISCONNECTED). 


Note: 


reason informs the reason of disconnection from: 
NET _HTTP_RC_DISC_BY_SERVER 
NET _HTTP_RC_DISC_BY_USER 

NET _HTTP_RC_SND_TIMEOUT 

NET _HTTP_RC_RCV_TIMEOUT 

NET _HTTP_RC_KEEPALIVE_TIMEOUT 
NET_HTTP_RC_ERR_INVALID_DATA 
NET _HTTP_RC_SSL_CLOSENOTIFY 
NET _HTTP_RC_SSL_HS_FAIL 
NET_HTTP_RC_SSL_ERR_GENERAL 
NET_HTTP_RC_TCP ERR_GENERAL 
NET_HTTP_RC_ERR_GENERAL 


Data Fields 


e NetHttpSesHandle ses 
e void * ses_user 
e int reason 


4.4.2 Field Documentation 
4.4.2.1 NetHttpSesHandle NetHttpEvinfoDisconnected::ses 


[in] Session handle 


4.4.2.2 voidx NetHttpEvinfoDisconnected::ses_user 


[in] User pointer for the session 


4.4.2.3 int NetHttpEvinfoDisconnected::reason 


[in] Reason of disconnection 


The documentation for this struct was generated from the following file: 


e nethttpif.h 
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4.5 NetHttpEvinfoHeaderBufRequired Struct Reference 


#include <nethttpif.h> 


4.5.1 Detailed Description 

Notify the receive header buffer is short (NET_HTTP_EV_HEADER_BUF_REQUIRED). The calling 
application should allocate a greater buffer for receiving the header part with realloc or similar way and 
return the pointer of the beginning of the buffer. The calling application must determine how big the new 


buffer should be. If your application does not specify the buffer size to use, use buffer size of 2Kbytes. 


Note: 


If the calling application cannot allocate enough memory, it should return without modifying the buffer 
pointer and its size. In this case, it should notify NET_HTTP_EV_TRANSACTION_ABORT (NET _- 
HTTP_RC_OUT_OF_MEMORY) to its transaction. 


Data Fields 


e NetHttpTrHandle tr 
e void x tr_user 

e void x header_buf 
e int header_bufsize 


4.5.2 Field Documentation 
4.5.2.1 NetHttpTrHandle NetHttpEvinfoHeaderBufRequired::tr 


[in] Transaction handle 


4.5.2.2 void» NetHttpEvinfoHeaderBufRequired::tr_user 


[in] User pointer for the transaction 


4.5.2.3 void» NetHttpEvinfoHeaderBufRequired::header_buf 


[in] The current receive header buffer [out ] Reallocated receive header buffer 


4.5.2.4 int NetHttpEvinfoHeaderBufRequired::header_bufsize 


[in] Length of the current buffer [out] Size of the reallocated buffer 


The documentation for this struct was generated from the following file: 


e nethttpif.h 
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4.6 NetHttpEvinfoNewBufRequired Struct Reference 


#include <nethttpif.h> 


4.6.1 Detailed Description 


Add request for received buffer (header and body) (NET_HTTP_EV_NEW_BUF_REQUIRED). 


This function is reported when receiving multiple response against one request. 


This function requests for additional receive buffer, when the library receives the buffer for only one re- 
sponse from the application, but receives multiple response from the server against NetHttpRequest. When 
this function is called, allocate a new receive buffer. 


Note: 


header_buf and header_bufsize give the information of receive header buffer. Specify the new allocated 
receive header buffer information in [out]. The minimum of 2Kbytes is recommended. 
content_buf and content_bufsize give the Information of receive body buffer. Specify the new allocated 
receive body buffer information in [out]. If your application does not specify the buffer size to use, 
use buffer size of 2Kbytes. 


Data Fields 


NetHttpTrHandle tr 
void x tr_user 


void * header_buf 


int header_bufsize 


void * content_buf 


int content_bufsize 


4.6.2 Field Documentation 
4.6.2.1 NetHttpTrHandle NetHttpEvinfoNewBufRequired::tr 


[in] Transaction handle 


4.6.2.2 void+ NetHttpEvinfoNewBufRequired::tr_user 


[in] User pointer for the transaction 


4.6.2.3 void+ NetHttpEvinfoNewBufRequired::header_buf 


[in] NULL [out] Receive header buffer 


4.6.2.4 int NetHttpEvinfoNewBufRequired::header_bufsize 


[in] 0 [out] Size of receive header buffer 
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4.6.2.5 void» NetHttpEvinfoNewBufRequired::content_buf 


[in] NULL [out] Receive body buffer 


4.6.2.6 int NetHttpEvinfoNewBufRequired::content_bufsize 


[in] O [out] Size of receive body buffer 


The documentation for this struct was generated from the following file: 


e nethttpif.h 
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4.7 NetHttpEvinfoReceivedContent Struct Reference 


#include <nethttpif.h> 


4.7.1 Detailed Description 
Notify reception of the response body has completed (NET_HTTP_EV_RECEIVED_CONTENT). 


Note: 


This event is reported when the whole body is completely received. 

On chunked reception, HTTPLib removes the chunk-size field and writes the remaining pure data into 
the receive body buffer. In other cases, the received data will be written to the buffer intact. Trailer is 
not notified. In case if there is no body part, content_len will be set as 0. 

current_content_len and current_content_buf contain the data information received between the 
timing of reporting NET_HTTP_EV_RECEIVED_HEADER or NET_HTTP_EV_RECEIVING_- 
CONTENT to the timing of receiving this event. 


Data Fields 


e NetHttpTrHandle tr 

e void * tr_user 

e int content_len 

e void * current_content_buf 
e int current_content_len 


4.7.2 Field Documentation 
4.7.2.1 NetHttpTrHandle NetHttpEvinfoReceivedContent::tr 


[in] Transaction handle 


4.7.2.2 void* NetHttpEvinfoReceivedContent::tr_user 


[in] User pointer for the transaction 


4.7.2.3 int NetHttpEvinfoReceivedContent::content_len 


[in] Total body length 


4.7.2.4 void+ NetHttpEvinfoReceivedContent::current_content_buf 


[in] Beginning of the data that has just written 


4.7.2.5 int NetHttpEvinfoReceivedContent::current_content_len 


[in] Length of the data that has just written 


The documentation for this struct was generated from the following file: 
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e nethttpif.h 
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4.8 NetHttpEvinfoReceivedHeader Struct Reference 


#include <nethttpif.h> 


4.8.1 Detailed Description 


Notify reception of the response header has completed (NET_HTTP_EV_RECEIVED_HEADER). 


Note: 


This event is reported when the whole header is completely received. The received data will be written 
to the buffer without any modifications. 

If Version is NET_HTTP_VERSION_0_9, the status code is 200. 

version parameter indicates the HTTP version in the response header. If Version is NET_HTTP_- 
VERSION_0_9, receive data is notified as a body. 

The following value is passed through content_len if the body length is unknown: 
NET_HTTP_CONTENT_LEN_CHUNK(-1) : In case of chunk encoding 
NET_HTTP_CONTENT_LEN_UNKNOWN(-2) : Chunk encoding is not used but there is no 
Content-Length header. 

If Version is NET_HTTP_VERSION_0_9, NET_HTTP_CONTENT_LEN_UNKNOWN is specified. 
The HEAD method request contains no body. The content_len is always zero (0) even if the request 
contains Content-Length. 


Warning: 


HTTPLib does not support "Content-Type: multipart" that is not accompanied by any one of "content- 
length," "Transfer-Encoding: chunked" or "Connection: Close." If this happens, the transaction and 
connection are terminated. In this case, this event will not be reported. 


Data Fields 


NetHttpTrHandle tr 


void * tr_user 


int status_code 


NetHttpVersion version 


void * header _buf 


int header_len 


int content_len 


4.8.2 Field Documentation 
4.8.2.1 NetHttpTrHandle NetHttpEvinfoReceivedHeader::tr 


[in] Transaction 


4.8.2.2 void» NetHttpEvinfoReceivedHeader::tr_user 


[in] User pointer for the transaction 
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4.8.2.3 int NetHttpEvinfoReceivedHeader::status_code 


[in] Status code 


4.8.2.4 NetHttpVersion NetHttpEvinfoReceivedHeader::version 


[in] HTTP version 


4.8.2.5 void» NetHttpEvinfoReceivedHeader::header_buf 


[in] Initial address of HTTP header 


4.8.2.6 int NetHttpEvinfoReceivedHeader::header_len 


[in] Header length incuding the blank line 


4.8.2.7 int NetHttpEvinfoReceivedHeader::content_len 


[in] Estimated body length 


The documentation for this struct was generated from the following file: 


e nethttpif.h 
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4.9 NetHttpEvinfoReceivingContent Struct Reference 


#include <nethttpif.h> 


4.9.1 Detailed Description 


Notify the reception of the response body is in progress (NET_HTTP_EV_RECEIVING_CONTENT). 


Note: 


This event is reported when it starts receiving the response body. 

When it receives the whole contents in one process, or if there is no body part, only NET_HTTP_EV_- 
RECEIVED_CONTENT will be reported and this event will not be reported. On chunked reception, 
HTTPLib removes the chunk-size field and writes the remaining pure data into the receive body buffer. 
Except this case, the received data will be written in the buffer with no edit. Trailer is not notified. 
current_content_len and current_content_buf contain the data information received between the 
timing of reporting NET_HTTP_EV_RECEIVED_HEADER or NET_HTTP_EV_RECEIVING_- 
CONTENT to the timing of receiving this event. 


Data Fields 


NetHttpTrHandle tr 


void * tr_user 


int content_len 


void * current_content_buf 


int current_content_len 


4.9.2 Field Documentation 
4.9.2.1 NetHttpTrHandle NetHttpEvinfoReceivingContent::tr 


[in] Transaction handle 


4.9.2.2 void+ NetHttpEvinfoReceivingContent::tr_user 


[in] User pointer for the transaction 


4.9.2.3 int NetHttpEvinfoReceivingContent::content_len 


[in] Length of the body already received 


4.9.2.4 void» NetHttpEvinfoReceivingContent::current_content_buf 


[in] Beginning of the data that has just written 
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4.9.2.5 int NetHttpEvinfoReceivingContent::current_content_len 


[in] Length of the data that has just written 


The documentation for this struct was generated from the following file: 


e nethttpif.h 
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4.10 NetHttpEvinfoReceivingHeader Struct Reference 


#include <nethttpif.h> 


4.10.1 Detailed Description 
Notify reception of the response header has started (NET_HTTP_EV_RECEIVING_HEADER). 


Note: 


This event will be reported when it receives the response header. When it receives the whole header 
part in one process, only NET_HTTP_EV_RECEIVED_HEADER will be reported and this event will 
not be reported. 


Data Fields 


e NetHttpTrHandle tr 
e void * tr_user 


4.10.2 Field Documentation 
4.10.2.1 NetHttpTrHandle NetHttpEvinfoReceivingHeader::tr 


[in] Transaction handle 


4.10.2.2 void» NetHttpEvinfoReceivingHeader::tr_user 


[in] User pointer for the transaction 


The documentation for this struct was generated from the following file: 


e nethttpif.h 
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4.11 NetHttpEvinfoSent Struct Reference 


#include <nethttpif.h> 


4.11.1 Detailed Description 


Notify the request has been sent (NET_HTTP_EV_SENT). 


Data Fields 


e NetHttpTrHandle tr 
e void x tr_user 


4.11.2 Field Documentation 
4.11.2.1 NetHttpTrHandle NetHttpEvinfoSent::tr 


[in] Transaction handle 


4.11.2.2 void» NetHttpEvinfoSent::tr_user 


[in] User pointer for the transaction 


The documentation for this struct was generated from the following file: 


e nethttpif.h 
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4.12 NetHttpEvinfoSsICertError Struct Reference 


#include <nethttpif.h> 


4.12.1 Detailed Description 


SSL server certificate error notification (NET_HTTP_EV_SSL_CERT_ERROR). 


This event is for notifying a server certificate error. When this error occurs, the calling application must 
decide whether or not communication should continue. Answer with OK or NG to continue SSL commu- 
nication. 


The process of same HTTP handling will be blocked until this callback is retuned. 


When there is user query while the server certification error has occurred, there are two options for Calling 
AP: 


1. Block the process of same HTTP handling, and operate user query. 


2. In order not to block the process of same HTTP handling, once return Connection resume NG, and then 
restart it from NetHttpStartSSL after the response from the user. (Restart it from NetHttpStartSSL after 
CONNECT method when using proxy) 


Note: 


the cause parameter inform the reason of the suspension as below. It notifies the logic operation AND 
of all the occured error:- 

NET_HTTP_RC_SSL_SCERT_PATHERR: "Server certificate chain construction error". This event 
is reported when it cannot construct the server certificate chain, since it cannot find the publisher’s 
certificate, while constructing the server certificate chain from server certificate to trust route CA cert. 
NET_HTTP_RC_SSL_SCERT_EXPIRE: "Certificate expire error". This event is reported when there 
is an expired server certificate, in the server certificate chain. 

NET_HTTP_RC_SSL_ SCERT_HOSTERR: "Host name error". This event is reported when the URL 
host name and the identity in server certificate does not match. 

The result parameter indicates to continue connection or not. 

When the communication resume is NG, we should notify to the server what error has caused NG. 
APL has to select the cause of the failure. Possible result values are:- 

NET_HTTP_SSL_START_OK : Communication resume OK 
NET_HTTP_SSL_START_NG_PATHERR : Communication resume NG (Does not receive server 
cert. chain construction error) 

NET_HTTP_SSL_START_NG_EXPIRE : Communication resume NG (Does not receive certificate 
expire error) 

NET_HTTP_SSL_START_NG_HOSTERR : Communication resume NG (Does not receive host 
name error) 


Data Fields 


e NetHttpSesHandle ses 
e void * ses_user 
e int cause 


e NetHttpSslCertErrorResult result 
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4.12.2 Field Documentation 
4.12.2.1 NetHttpSesHandle NetHttpEvinfoSsICertError::ses 


[in] Session handle 


4.12.2.2 void» NetHttpEvinfoSslCertError::ses_user 


[in] User pointer for the session 


4.12.2.3 int NetHttpEvinfoSslCertError::cause 


[in] Reason of suspension 


4.12.2.4 NetHttpSslCertErrorResult NetHttpEvinfoSslCertError::result 


[in] Continue connection OK [out] Continue connection OK or NG 


The documentation for this struct was generated from the following file: 


e nethttpif.h 
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4.13 NetHttpEvinfoSslClose Struct Reference 


#include <nethttpif.h> 


4.13.1 Detailed Description 


SSL terminate notification (NET_HTTP_EV_SSL_CLOSE). 


This event is reported when SSL is terminated. When this event is reported, call NetHttpStopSSL. 


Note: 


reason parameter inform the reason of termination:- 
NET_HTTP_RC_DISC_BY_SERVER 
NET_HTTP_RC_DISC_BY_USER 
NET_HTTP_RC_SND_TIMEOUT 
NET_HTTP_RC_RCV_TIMEOUT 
NET_HTTP_RC_KEEPALIVE_TIMEOUT 
NET_HTTP_RC_ERR_INVALID_DATA 
NET_HTTP_RC_SSL_CLOSENOTIFY 
NET_HTTP_RC_SSL_HS_FAIL 
NET_HTTP_RC_SSL_ERR_GENERAL 
NET_HTTP_RC_TCP ERR_GENERAL 
NET_HTTP_RC_ERR_GENERAL 


Data Fields 


e NetHttpSesHandle ses 
e void * ses_user 
e int reason 


4.13.2 Field Documentation 
4.13.2.1 NetHttpSesHandle NetHttpEvinfoSslClose::ses 


[in] Session handle 


4.13.2.2 void» NetHttpEvinfoSsIClose::ses_user 


[in] User pointer for the session 


4.13.2.3 int NetHttpEvinfoSsIClose: :reason 


[in] Reason of termination 


The documentation for this struct was generated from the following file: 


e nethttpif.h 
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4.14 NetHttpEvinfoSslHsEnd Struct Reference 


#include <nethttpif.h> 


4.14.1 Detailed Description 


Notify the SSL handshaking termination (NET_HTTP_EV_SSL_HS_END). 


This event is notified when SSL handshaking is terminated. 


Note: 


result parameter informs the handshake result as:- 
NET_HTTP_RC_SUCCESS : Succeeded in handshaking. 
NET_HTTP_RC_SSL_HS_FAIL : Failed in handshaking. 


Data Fields 


e NetHttpSesHandle ses 
e void * ses_user 
e int result 


4.14.2 Field Documentation 
4.14.2.1 NetHttpSesHandle NetHttpEvinfoSsIHsEnd::ses 


[in] Session handle 


4.14.2.2 void» NetHttpEvinfoSsIHsEnd::ses_user 


[in] User pointer for the session 


4.14.2.3 int NetHttpEvinfoSsIHsEnd::result 


[in] Handshake result 


The documentation for this struct was generated from the following file: 


e nethttpif.h 
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4.15 NetHttpEvinfoSslHsStart Struct Reference 


#include <nethttpif.h> 


4.15.1 Detailed Description 


Notify the SSL handshaking establishment (NET_HTTP_EV_SSL_HS_START). 


Data Fields 


e NetHttpSesHandle ses 
e void * ses_user 


4.15.2 Field Documentation 
4.15.2.1 NetHttpSesHandle NetHttpEvinfoSslHsStart::ses 


[in] Session handle 


4.15.2.2 void» NetHttpEvinfoSsIHsStart::ses_user 


[in] User pointer for the session 


The documentation for this struct was generated from the following file: 


e nethttpif.h 
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4.16 NetHttpEvinfoTransactionAbort Struct Reference 


#include <nethttpif.h> 


4.16.1 Detailed Description 


Notify the transaction has been aborted (NET_HTTP_EV_TRANSACTION_ABORT). 


This is reported when the transaction is failed (timeout, connection termination, etc.). When this function 
is reported, NetHttpDeleteTransaction will be called. 


Note: 


the reason of transaction failure can be: 
NET_HTTP_RC_DISC_BY_SERVER 
NET_HTTP_RC_SND_TIMEOUT 
NET_HTTP_RC_RCV_TIMEOUT 
NET_HTTP_RC_KEEPALIVE_TIMEOUT 
NET_HTTP_RC_OUT_OF_MEMORY 
NET_HTTP_RC_CANCELED 
NET_HTTP_RC_ERR_INVALID_DATA 
NET_HTTP_RC_SSL_ERR_GENERAL 
NET_HTTP_RC_TCP ERR_GENERAL 
NET_HTTP_RC_ERR_GENERAL 


Data Fields 


e NetHttpTrHandle tr 
e void x tr_user 
e int reason 


4.16.2 Field Documentation 
4.16.2.1 NetHttpTrHandle NetHttpEvinfoTransactionAbort::tr 


[in] Transaction handle 


4.16.2.2 void» NetHttpEvinfoTransactionAbort::tr_user 


[in] User pointer for the user 


4.16.2.3 int NetHttpEvinfoTransactionAbort::reason 


[in] Error code 


The documentation for this struct was generated from the following file: 


e nethttpif.h 
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4.17 NetHttpEvinfoTransactionComplete Struct Reference 


#include <nethttpif.h> 


4.17.1 Detailed Description 


Notify the transaction has completed (NET_HTTP_EV_TRANSACTION_COMPLETE). 


This is reported after the transaction. When this function is reported, NetHttpDeleteTransaction will be 
called. 


Data Fields 


e NetHttpTrHandle tr 
e void x tr_user 


4.17.2 Field Documentation 
4.17.2.1 NetHttpTrHandle NetHttpEvinfoTransactionComplete::tr 


[in] Transaction 


4.17.2.2 void» NetHttpEvinfoTransactionComplete::tr_user 


[1n] User pointer for the transaction 


The documentation for this struct was generated from the following file: 


e nethttpif.h 
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Chapter 5 


File Documentation 


5.1 ComponentOverview.h File Reference 


5.1.1 Detailed Description 


Component Programming Interface Overview Header Template for Doxygen. 


This file contains configuration information for documentation generation; it does not contain any API- 
specific information. 
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5.2 httpMSCs.h File Reference 


5.2.1 Detailed Description 


Illustrative HTTP API Call Sequence Charts. 


This file contains configuration information for documentation generation; it does not contain any API- 
specific information. 


NET HTTP | QISCONNECTEDINET HITE RO DISC EY USER 


Figure 5.1: 1-1. Basic sequence 
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Assume server response looks like: 
NET_HTTP_EV_RECEIVING HEADER) 


[Header1234 |body12345687890 | 
LF SS / 
header body 


Figure 5.2: 1-2. Header receive buffer is short 
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NET_HTTP_EV_RECEIVING CONTENT 


Figure 5.3: 1-3. Body receive buffer is short 
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INetHttolnitialize 


NetHttoNewSession 


NetHttoNewTransaction 
eturn 


NetHttpReauest(tr=1) 


+ 


Calling App must check 
if the server supports 

pipelining and can start 
the next transaction. 


return(tr=2 


INetHttpRequest(tr=2) 
en 
Ne send 


INetHttoNewTransaction 

NetHttpReauest(tr=3) 

E return 
REN RESET PENA NET HTTP EV SENT(tr=2) 


send 
= = NET HTTP EV SENT(tr=3) 


return 


pov 


__NET_HTTP_EV_RECEIVED_CONTENT(tr=1) 


ret M rr 
— NET_HTTP_EV_TRANSACTION COMPLETE(tr=1) 


return 


recv 


return 


Figure 5.4: 1-4. Basic pipelining sequence 
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NET_HTTP_EV_SENT 


100 Response 


100 Response continued 
2000K Response 


NET_HTTP_EV_RECEIVED_CONTENT(100 Response) 


2000K Response continued 


_NET_HTTP_EV_RECEIVED_C NT 


NET_HTTP_EV_TRANSACTION COMPLETE 


Figure 5.5: 1-5. A transaction with two responses 
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return 


return 


Figure 5.6: 1-6. User cancelled 


NetHttpNewTransaction 


Response received 


KeepAliveTimer 


S? 
RY TimerStop 
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N SendTimer 
a meee EHE EN 
return 
TimerOut 

NET HTTP EV TRANSACTION ABORT(NET HTTP RC SND TIMEQU 

return 

[NetHttoDelete Transaction 

NET HTTP Ey DISCONNECTED(NET HTTP RC SND TIMEOU' 
return dl 
4 retui 


NET HTTP EV TRANSACTION ABORT(NET HTTP RC RCV 


return 


INetHttpDeleteTransaction 
NET HTTP By DISCQNNECTESWET HTIPRERCVTIMEOUD 


returi 


return 


TimerOut 


return 


Figure 5.7: 1-7. Timer 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


5.2 httpMSCs.h File Reference 


43 


NetHttolnitialize 


NetHttoNewSession 


NetHttoNewTransaction 


NetHttoAddHeader 


NetHttpSetContentChunk(content end=OFF) 
e Fr ra re ae are re 
NetHttpReauest 


V_SENT notified when data sending 
with 
NetHttoSetContent(content_end=ON) 


—.NETHTTP.EV.SEN 


NetHittpDeleteTransaction 


INetHitpDeleteSession 


return 


NetHitpFinalize 


Figure 5.8: 1-8. Chunk transmission 
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NET HTTP EV CONTENT BUF REQUIRED 


æ m EE R RE EPE EI 
urn 


=. -NET HTIP.EV RECEIVED. CONTENT. 


return 


„un; IET ATI EV TRANSACTION COMPLETE 


Transacton 


Figure 5.9: 1-9 part 1. Chunk size notification 
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NET_HTTP_EY DISCONNECTEDINET HTTP. RO DISC BY USER) 


return 


return 


Figure 5.10: 1-9 part 2. Chunk size notification 
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=.=.. NETHTTF.EY RECEIVED, CONTEN 


stumm 


fotus 


e- NET-HTIP.FWTBANSACTION COMPLETE 


Figure 5.11: 1-9 part 3. Chunk size notification 
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NET HTTP, EV RECEIVING CONTEN 


SH PIERRE 


[ettuzDeieteTrareacien 


Figure 5.12: 1-9 part 4. Chunk size notification 
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Initialize 


return 


NetHttpNewSession 


NetHttoNewTransaction(ConnectMethod) 


NetHttpAddHeader 


These sequences 
are not executed if 
no tunneling is 


Response 


_NET.HTTP EV, REGEVED_ CONTENT 


_. _. NELHTTP.EV_TRANSAOTION COMPLETE 


NetHttpDeleteTransaction 


SSL start 


returr 


NetHttoRequest(tr=2) 


Request 
ES ET _ _NET.HTTP_EV.SENT 

Response 
NET_HTTP_EV_RECEIVED HEADER 


NET_HTTP_EV_TRANSACTION_COMPLETE 


NetHttpDeleteTransaction 


returr 


SSL 


NetHttoStopSSL 


terminated 


return 


NetHttoDeleteSession 


NET_HT JP EV DISCONNECTED(NET_HTTP_RC DISC BY USER) 
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Ne pFinalize 


Figure 5.13: 2-1. Basic SSL sequence (with tunnelling) 
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return(tr=2) 


NetHttpRequest(tr=2) 


NetHttpDelete Transaction 


NET HIJP EV SS*-ClOSE(NET,HTTP_RC DISC. BY SERVER) _ 


NET HTTP Ey DISCONNECTED(NET HTTPRGRISC BY SERVER) 


return 


INetHttpStopSSL 
retum 


NetHttpRequest(tr=2) 
return 


Request 


NetHttpRequest(tr=3) 
EIN 


NET HTTP_EV_TRANSACTION ABORT(NET,HTTP.RC, 


NET_HTTP EV DISCONNECTED(NET HTTP_RC DISC BY 


return 


return(NET_HTTP_RC_SSL_ALREADY_CLOSE) 


NetHttpRequest(tr=4) 
return(NET_HTTP_RC_SSL_ALREADY_CLOSE 


retum(NET_HTTP_RC_SUCCESS) 


Figure 5.14: 2-2. Network disconnected SSL 
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NET HTTP.&V TRANSACTION ABORT(NET HTTP.RC_CANCELED 


Ne pNewTransaction 


return(tr=2 


NetHttpRequest(tr=2) 


Figure 5.15: 2-3. User cancelled SSL 
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return 


NET_HTTP_EV_SSLHS STAR 


¿momo e: — NETHTTP_EV_SSL_CERT_ERROR 
'eturn(Cont OK) > 


NET_HTTP_EV_SSLHS_END (NET HTTP RC_SUCCESS) 


return(tr= 


NET_HTTP EV SSL_CERT ERROR 


return (Cont NG) 


NET_HTTP_EV_SSLHS_END (NET HTTP RC SSL HS FAIL) 


HTTP EV SSL CLOSE(NET HTTP_RC SSL_HS FAN 


Figure 5.16: 2-4. Non-fatal error in SSL handshaking (without user query) 
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NetHttpStartSSL 


return 


_NET.HTTP_EV SSLHS START 


> 


> 


AAA i 


return (Cont NG) > 


NE HITE EV SSL CLOSE(NET HTTP RC.SSL.HS,FAIL) 


NET_HT¿P EV DISCONNECTED(NET HTTP RC SSL HS FAI 
return 


NetHttpStopSSt 


return 


Figure 5.17: 2-5-1. 
HTTPLib) 


Non-fatal error in SSL handshaking (with user query : 


To block the process of 
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NetHttpNewSession 


Establish tunnelling (see 2-1) 


NetHttpStartSSL 


NET_HTJP EV DISCONNECTED(NET HTTP_RC SSL_HS FAI 


woh nora 
return 


ait until the user 
replied what to do, 
and do the rest of 
the processing. 


NetHttpStopSSL 


Sr eee 
Establish tunnelling (see 2-1) 


Restart with 
CONNECT. 


NetHttpStartSSL 


eturn (Cont OK) 


NET.HTTP.EV.SSL HS END (NET HTTP_RC_SUCCESS) 


NetHttpNewTransaction 


return(tr=2) 


NetHttpDeleteSession 


return 
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5.3 httpSuppInfo.h File Reference 


5.3.1 Detailed Description 


Open SSL related supplementary information. 


This file contains configuration information for documentation generation; it does not contain any API- 
specific information. 


5.3.2 SSL 
5.3.2.1 Default of secret code list and the detail 


The default of OpenSSL, CipherList is as below (in case of using OpenSSL-0.9.8e): 
TLS_DHE_RSA_WITH_AES_256_CBC_SHA = { 0x00, 0x39 } 
TLS_DHE_DSS_WITH_AES_256_CBC_SHA = { 0x00, 0x38 } 
TLS_RSA_WITH_AES_256_CBC_SHA = { 0x00, 0x35 } 
TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA = { 0x00, 0x16 } 
TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA = { 0x00, 0x13 } 
TLS_RSA_WITH_3DES_EDE_CBC_SHA = { 0x00, 0x0A } 
SSL_CK_DES_192_EDE3_CBC_WITH_MDS = { 0x07, 0x00, OxCO } 
TLS_DHE_RSA_WITH_AES_128_CBC_SHA = { 0x00, 0x33 } 
TLS_DHE_DSS_WITH_AES_128_CBC_SHA = { 0x00, 0x32 } 
TLS_RSA_WITH_AES_128_CBC_SHA = { 0x00, 0x2F } 
TLS_RSA_WITH_IDEA_CBC_SHA = { 0x00, 0x07 } 

SSL_CK_IDEA_ 128 _CBC_WITH_MDS = { 0x05, 0x00, 0x80 } 
SSL_CK_RC2_128_CBC_WITH_MDS = { 0x03, 0x00, 0x80 } 
TLS_RSA_WITH_RC4_128_SHA = { 0x00, 0x05 } 
TLS_RSA_WITH_RC4_128_MD5 = { 0x00, 0x04 } 
SSL_CK_RC4_128_WITH_MDS = { 0x01, 0x00, 0x80 } 
TLS_DHE_RSA_WITH_DES_CBC_SHA = { 0x00, 0x15 } 
TLS_DHE_DSS_WITH_DES_CBC_SHA = { 0x00, 0x12 } 
TLS_RSA_WITH_DES_CBC_SHA = { 0x00, 0x09 } 
SSL_CK_DES_64_CBC_WITH_MDS = { 0x06, 0x00, 0x40 } 
TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA = { 0x00, 0x14 } 
TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA = { 0x00, Ox11 } 
TLS_RSA_EXPORT_WITH_DES40_CBC_SHA = { 0x00, 0x08 } 
TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 = { 0x00, 0x06 } 
SSL_CK_RC2_128_CBC_EXPORT40_WITH_MDS = { 0x04, 0x00, 0x80 } 
TLS_RSA_EXPORT_WITH_RC4_40_MD5 = { 0x00, 0x03 } 
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SSL_CK_RC4_128_ EXPORT40_WITH_MD5 = { 0x02, 0x00, 0x80 } 
Description of CIPHER LIST FORMAT is as below: 
Ex 1) "ALL:!ADH:+RC4: @STRENGTH" 


Ex 2) "DHE-RSA-AES256-SHA:DHE-DSS-AES256-SHA:AES256-SHA:EDH-RSA-DES-CBC3- 
SHA:EDH-DSS-DES-CBC3-SHA: DES-CBC3-SHA:DES-CBC3-MD5:DHE-RSA-AES 128-SHA:DHE- 
DSS-AES128-SHA:AES128-SHA:IDEA-CBC-SHA:IDEA-CBC-MDS: RC2-CBC-MD5:RC4- 
SHA:RC4-MDS5:RC4-MD5:EDH-RSA-DES-CBC-SHA:EDH-DSS-DES-CBC-SHA:DES-CBC- 
SHA:DES-CBC-MD5: | EXP-EDH-RSA-DES-CBC-SHA:EXP-EDH-DSS-DES-CBC-SHA:EXP-DES- 
CBC-SHA:EXP-RC2-CBC-MD5:EXP-RC2-CBC-MD5: EXP-RC4-MD5:EXP-RC4-MD5" 


See OpenSSL manual for the detail. 


5.3.2.2 Relation of session and SSL 


Specify SSL ON/OFF in each session. 


So, the session using NetHttpStartSSL establish SSL communication, and the session which doesn’t use 
NetHttpStartSSL establish the communication without SSL. The library does not consider the Request 
URI. 


HTTP library will send the request with no check, even when "RequestURI http://xxx" is specified un- 
der SSL session. Also, HTTP library will send the request with no check, even when "RequestURI 
https: //xxx" is specified under non-SSL session. Therefore, under SSL session, Calling application 
can only specify "https://xxx" as a Request URI, and when it specifies "http://xxx", it should be controlled 
to establish a different session. 


5.3.2.3 Establish tunneling 


Tunneling establishment using Connect method should be done by Calling application. 


5.3.2.4 Certificate storage 


Trusted-Root CA certificate file should be stored as below: 


The certificate should be stored under the directry "$HOME/certificates/", with the rule below in DER 
format. 


rootca??.der : "??" is decimal value with double digit (00 to 99) 


5.3.2.5 Timer 


HTTP library provides the timer as below. Calling application can specify in NetHttplnitialize if necessary: 


When timeout occurs, report NET_HTTP_EV_TRANSACTION_ABORT to all the transaction that re- 
quests NetHttpRequest. Then, connection will be terminated. 


SendTimer : Boots when request is completely sent. It ends when it starts receiving response. 


ReceiveTimer : Boots while receiving the data from the timing when it starts receiving response to the 
timing it ends receiving response completely. It ends when receiving the next data. 


Keep-AliveTimer : Boots when the response is received completely. It ends when start sending another 
request, or when it receives FIN. 
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5.3.2.6 Other Restrictions 


The maximum request or response size the HTTPLib can handle is 2Gbytes. If the response more 
than this size is received, the connection will be disconnected; the return value of NET _HTTP_EV_- 
DISCONNECTED is NET_HTTP_RC_ERR_INVALID_DATA. 
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5.4 nethttpif.h File Reference 


5.4.1 Detailed Description 


LiMo HTTP Library API Header. 


Data Structures 


Defines 


#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 


struct NetHttpSsICtxParam 

struct NetHttpEvinfoConnected 

struct NetHttpEvinfoDisconnected 

struct NetHttpEvinfoHeaderBufRequired 
struct NetHttpEvinfoContentBufRequired 
struct NetHttpEvinfoSent 

struct NetHttpEvinfoReceivingHeader 
struct NetHttpEvinfoReceivedHeader 
struct NetHttpEvinfoReceivingContent 
struct NetHttpEvinfoReceivedContent 
struct NetHttpEvinfoTransactionComplete 
struct NetHttpEvinfoTransactionAbort 
struct NetHttpEvinfoNewBufRequired 
struct NetHttpEvinfoSslHsStart 

struct NetHttpEvinfoSsIHsEnd 

struct NetHttpEvinfoSslCertError 

struct NetHttpEvinfoSslClose 

struct NetHttpEvent 


#define NET_HTTP_RC_SUCCESS 0 
NET_HTTP_RC_ERR_PARAM -1 


NET_HTTP_RC_OPERATION_FAILED -2 
NET_HTTP_RC_DISC_BY_SERVER -3 


NET_HTTP_RC_DISC_BY_USER -4 


NET_HTTP_RC_SND_TIMEOUT -5 


NET_HTTP_RC_RCV_TIMEOUT -6 


NET_HTTP_RC_KEEPALIVE_TIMEOUT -7 
NET_HTTP_RC_OUT_OF_MEMORY -8 


NET 


HTTP 


RC 


NET_HTTP_RC_CANCELED -9 


ERR_INVALID_DATA -10 


NET 


HTTP 


RC 


SSL_HS_FAIL -11 


NET 


HTTP 


RC 


SSL_ALREADY_CLOSE -12 


NET 


HTTP 


RC 


SSL_END_BY_SERVER -13 


NET 


HTTP 


RC 


SSL_CLOSENOTIFY -17 


NET 


HTTP 


RC 


SSL_ERR_GENERAL -18 


NET 


HTTP 


RC 


ERR_DNS -199 


NET 


HTTP 


RC 


ERR_PORTING -200 


NET 


HTTP 


RC 


TCP_ERR_GENERAL -19 


NET 


HTTP 


RC 


ERR_GENERAL -20 
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#define NET_HTTP_CONTENT_LEN_CHUNK (-1) 
#define NET_HTTP_CONTENT_LEN_UNKNOWN (-2) 
#define NET_HTTP_SSL_OP_SSL2 0x00000001 

#define NET_HTTP_SSL_OP_SSL3 0x00000002 

#define NET_HTTP_SSL_OP_TLS1 0x00000004 

#define NET_HTTP_SSL_SCERT_PATHERR 0x00000001 
#define NET_HTTP_SSL_SCERT_EXPIRE 0x00000002 
#define NET_HTTP_SSL_SCERT_HOSTERR 0x00000004 


Typedefs 


e typedef void x NetHttpHandle 

e typedef void x NetHttpSesHandle 

e typedef void x NetHttpTrHandle 

e typedef void(x) NetHttpCallback (NetHttpEvent xevent) 


Enumerations 


e enum NetHttpEventld { 


NET_HTTP_EV_CONNECTED, NET_HTTP_EV_DISCONNECTED, NET_HTTP_EV_- 
HEADER_BUF_REQUIRED, NET_HTTP_EV_CONTENT_BUF_REQUIRED, 


NET_HTTP_EV_SENT, NET_HTTP_EV_RECEIVING_HEADER, NET_HTTP_EV_- 
RECEIVED_HEADER, NET_HTTP_EV_RECEIVING_CONTENT, 


NET_HTTP_EV_RECEIVED_CONTENT, NET_HTTP_EV_TRANSACTION_COMPLETE, 
NET_HTTP_EV_TRANSACTION_ABORT, NET_HTTP_EV_NEW_BUF_REQUIRED, 


NET_HTTP_EV_SSL_HS_START, NET_HTTP_EV_SSL_HS_END, NET_HTTP_EV_SSL_- 
CERT_ERROR, NET_HTTP_EV_SSL_CLOSE } 

enum NetHttpLayer4 { NET_HTTP_LAYER4_TCP, NET_HTTP_LAYER4_WTCP } 

enum NetHttpVersion { NET_HTTP_VERSION_0_9, NET_HTTP_VERSION_1_0, NET_HTTP_- 
VERSION_1_1 } 

enum NetHttpFlag { NET_HTTP_OFF, NET_HTTP_ON } 

enum NetHttpSslCertErrorResult { NET_HTTP_SSL_START_OK, NET_HTTP_SSL_START_- 
NG_PATHERR, NET_HTTP_SSL_START_NG_EXPIRE, NET_HTTP_SSL_START_NG _- 
HOSTERR } 


Functions 


e int NetHttpInitialize (NetHttpCallback cb, NetHttpHandle xhttp, int snd_timer, int rcv_timer, int 
keep_alive_timer, const NetHttpSsICtxParam x*ctx_param) 


HTTP Lib initialization processing. 


e int NetHttpFinalize (NetHttpHandle http) 
Perform cleanup operation for HTTP Lib. 


e int NetHttpNewSession (NetHttpSesHandle xses, NetHttpHandle http, const char x*dest_name, int 
dest_port, NetHttpLayer4 layer4, const char «device, void *ses_user) 


Creates a new session. 
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int NetHttpDeleteSession (NetHttpSesHandle ses) 


Release the session. 


int NetHttpNewTransaction (NetHttpTrHandle «tr, const void *requestline, int requestline_len, const 
void xheader, int header_len, void *tr_user) 


Create a new transaction. 


int NetHttpDeleteTransaction (NetHttpTrHandle tr) 


Release the transaction. 


int NetHttpAddReqHeader (NetHttpTrHandle tr, const void xheader, int header_len) 
Add a request header. 


int NetHttpSetReqContent (NetHttpTrHandle tr, const void «content, int content_len) 


Set a request body. 


int NetHttpSetReqContentChunk (NetHttpTrHandle tr, const void «content, int content_len, Net- 
HttpFlag content_end) 


Set a request body in chunk sending. 


int NetHttpRequest (NetHttpSesHandle ses, NetHttpTrHandle tr, void *header_buf, int header_- 
bufsize, void *content_buf, int content_bufsize) 


Start sending the request. 


int NetHttpDisconnect (NetHttpSesHandle ses) 


Disconnection process (User cancel). 


int NetHttpStartSSL (NetHttpSesHandle ses, const char xhostname, int hostname_len) 
Request SSL establishment. 


int NetHttpStopSSL (NetHttpSesHandle ses) 


SSL termination request. 


5.4.2 Define Documentation 


5.4.2.1 #define NET_HTTP_CONTENT_LEN_CHUNK (-1) 


In case of chunk encoding 


5.4.2.2 #define NET_HTTP_CONTENT_LEN_UNKNOWN (-2) 


Chunk encoding is not used but there is no Content-Length header 


5.4.2.3 #define NET_HTTP_RC_CANCELED -9 


Transaction cancel 
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5.4.2.4 #define NET_HTTP_RC_DISC_BY_SERVER -3 


Disconnection from the server 


5.4.2.5 #define NET_HTTP_RC_DISC_BY_USER -4 


Disconnection by the user 


5.4.2.6 #define NET_HTTP_RC_ERR_DNS -199 


DNS query error. see framework API for details 


5.4.2.7 #define NET_HTTP_RC_ERR_GENERAL -20 


Errors except above and SSL errors 


5.4.2.3 #define NET_HTTP_RC_ERR_INVALID_DATA -10 


Invalid data received 


5.4.2.9 #define NET_HTTP_RC_ERR_PARAM -1 


Parameter error 


5.4.2.10 #define NET_HTTP_RC_ERR_PORTING -200 


OEM specific error. see framework API for details 


5.4.2.11 #define NET_HTTP_RC_KEEPALIVE_TIMEOUT -7 


Keep-Alive timeout 


5.4.2.12 #define NET_HTTP_RC_OPERATION_FAILED -2 


Operation error 


5.4.2.13 #define NET_HTTP_RC_OUT_OF_MEMORY -8 


Out of memory 


5.4.2.14 #define NET_HTTP_RC_RCV_TIMEOUT -6 


RCV timeout 
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5.4.2.15 #define NET_HTTP_RC_SND_TIMEOUT -5 


Send timeout 


5.4.2.16 #define NET_HTTP_RC_SSL_ALREADY_CLOSE -12 


Suspend SSL (Transaction cannot be used) 


5.4.2.17 #define NET_HTTP_RC_SSL_CLOSENOTIFY -17 


received CloseNotify 


5.4.2.18 #define NET_HTTP_RC_SSL_END_BY_SERVER -13 


SSL termination from the server 


5.4.2.19 #define NET_HTTP_RC_SSL_ERR_GENERAL -18 


SSL error except above 


5.4.2.20 #define NET_HTTP_RC_SSL_HS_FAIL -11 


Handshake failure 


5.4.2.21 #define NET_HTTP_RC_SUCCESS 0 


Succeed 


5.4.2.22 #define NET_HTTP_RC_TCP_ERR_GENERAL -19 


TCP related error 


5.4.2.23 #define NET_HTTP_SSL_OP_SSL2 0x00000001 


SSLver2 


5.4.2.24 #define NET_HTTP_SSL_OP_SSL3 0x00000002 


SSLver3 


5.4.2.25 #define NET_HTTP_SSL_OP_TLS1 0x00000004 


TLSverl 
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5.4.2.26 #define NET_HTTP_SSL_SCERT_EXPIRE 0x00000002 


Certification expire error 


5.4.2.27 #define NET_HTTP_SSL_SCERT_HOSTERR 0x00000004 


Host name error 


5.4.2.28 #define NET_HTTP_SSL_SCERT_PATHERR 0x00000001 


Cerver cert. chain construction error 


5.4.3 Typedef Documentation 
5.4.3.1 typedef void(x) NetHttpCallback(NetHttpE vent xevent) 


Callback Function Type 


5.4.3.2 typedef void» NetHttpHandle 


HTTP Handle 


5.4.3.3 typedef void» NetHttpSesHandle 


Session Handle 


5.4.3.4 typedef void NetHttpTrHandle 


Transaction Handle 


5.4.4 Enumeration Type Documentation 
5.4.4.1 enum NetHttpEventld 


Callback Event ID 


Enumerator: 
NET_HTTP_EV_CONNECTED Notify the connection establishment is completed 
NET_HTTP_EV_DISCONNECTED Notify the connection termination is completed 
NET_HTTP_EV_HEADER_BUF_REQUIRED Demand additional receive buffer for header 
NET_HTTP_EV_CONTENT_BUF_REOUIRED Demand additional receive buffer for body 
NET_HTTP_EV_SENT Notify the request has been successfully sent 
NET_HTTP_EV_RECEIVING_HEADER Notify the response header is being received 
NET_HTTP_EV_RECEIVED_HEADER Notify the response body was successfully received 
NET_HTTP_EV_RECEIVING_CONTENT Notify the response body is being received. 
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NET_HTTP_EV_RECEIVED_CONTENT Notify the response body was successfully received 
NET_HTTP_EV_TRANSACTION_COMPLETE Notify the successful transaction completion 


NET_HTTP_EV_TRANSACTION_ABORT Notify abnormal termination of transaction 
NET_HTTP_EV_NEW_BUF_REQUIRED Add request for received buffer (header and body) 
NET_HTTP_EV_SSL_HS_START Notify the SSL handshaking establishment 
NET_HTTP_EV_SSL_HS_END Notify the SSL handshaking termination 
NET_HTTP_EV_SSL_CERT_ERROR SSL server cert error notification 
NET_HTTP_EV_SSL_CLOSE SSL terminate notification 


5.4.4.2 enum NetHttpFlag 
General Flag 


Enumerator: 


NET_HTTP_OFF OFF 
NET_HTTP_ON ON 


5.4.4.3 enum NetHttpLayer4 


Network Classification 


Enumerator: 


NET_HTTP_LAYER4_TCP use Linux Standard TCP 
NET_HTTP_LAYER4_WTCP use WTCP 


5.4.4.4 enum NetHttpSslCertErrorResult 


SSL Cert Error Result 


Enumerator: 
NET_HTTP_SSL_START_OK Accept to continue SSL 
NET_HTTP_SSL_START_NG_PATHERR Reject to continue SSL because of path error 
NET_HTTP_SSL_START_NG_EXPIRE Reject to continue SSL because of expired cert 
NET_HTTP_SSL_START_NG_HOSTERR Reject to continue SSL because of bad hostname 


5.4.4.5 enum NetHttp Version 


HTTP version 


Enumerator: 


NET_HTTP_VERSION_0_9 HTTP/0.9 
NET_HTTP_VERSION_1_0 HTTP/1.0 
NET_HTTP_VERSION_I_I HTTP/1.1 
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5.4.5 Function Documentation 


5.4.5.1 int NetHttpAddReqHeader (NetHttpTrHandle tr, const void x header, int header_len) 


Add a request header. 


Parameters: 


— tr transaction handle. 
— header request header. 


— header_len length of header. 


Return values: 


HTTP_RC_SUCCESS success. 


negative-value error. reason code returned. 


Note: 
Do not call this function in callback function from HTTP-Lib. 


5.4.5.2 int NetHttpDeleteSession (NetHttpSesHandle ses) 


Release the session. 


Parameters: 


<— ses session handle. 


Return values: 


HTTP_RC_SUCCESS success. 


negative-value error. reason code returned. 


Note: 
Do not call this function in callback function from HTTP-Lib. 


5.4.5.3 int NetHttpDeleteTransaction (NetHttpTrHandle tr) 


Release the transaction. 


Parameters: 


< tr transaction handle. 


Return values: 


HTTP_RC_SUCCESS success. 


negative-value error. reason code returned. 


Note: 


Do not call this function in callback function from HTTP-Lib. 
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5.4.5.4 int NetHttpDiscomnect (NetHttpSesHandle ses) 
Disconnection process (User cancel). 


Parameters: 


< ses session handle. 


Return values: 


HTTP_RC_SUCCESS success. 


negative-value error. reason code returned. 


Note: 


Do not call this function in callback function from HTTP-Lib. 


5.4.5.5 int NetHttpFinalize (NetHttpHandle http) 
Perform cleanup operation for HTTP Lib. 


Parameters: 


— http HTTP handle. 


Return values: 


HTTP_RC_SUCCESS success. 


negative-value error. reason code returned. 


Note: 


Do not call this function in callback function from HTTP-Lib. 


5.4.5.6 int NetHttpInitialize (NetHttpCallback cb, NetHttpHandle x http, int snd_timer, int 
rcv_timer, int keep_alive_timer, const NetHttpSsICtxParam x ctx_param) 


HTTP Lib initialization processing. 


Parameters: 
<—cb callback function pointer. 
— http HTTP handle. 
< snd_timer SEND timer. 
— rcv_timer RECEIVE timer. 
— keep_alive_timer KEEP-ALIVE timer. 


— ctx_param SSL context parameter. 


Return values: 


HTTP_RC_SUCCESS success. 


negative-value error. reason code returned. 
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5.4.5.7 int NetHttpNewSession (NetHttpSesHandle x ses, NetHttpHandle http, const char x 
dest_name, int dest_port, NetHttpLayer4 layer4, const char x device, void x ses_user) 


Creates a new session. 


Parameters: 


— ses session handle. 

— http HTTP handle. 

— dest_ name destination name. 

— dest_port destination port number. 
— layer4 layer4 protocol (TCP/WTCP). 
— device device name. 


— ses_user user pointer for the session. 


Return values: 


HTTP_RC_SUCCESS success. 


negative-value error. reason code returned. 


Note: 


Do not call this function in callback function from HTTP-Lib. 


5.4.5.8 int NetHttpNewTransaction (NetHttpTrHandle x tr, const void x requestline, int 
requestline_len, const void x header, int header_len, void x tr_user) 


Create a new transaction. 


Parameters: 


— tr transaction handle. 

— requestline request line. 

— requestline_len length of requestline. 
— header request header. 


— header_len length of header. 


Return values: 


HTTP_RC_SUCCESS success. 


negative-value error. reason code returned. 


5.4.5.9 int NetHttpRequest (NetHttpSesHandle ses, NetHttpTrHandle tr, void x header_buf, int 
header_bufsize, void x content_buf, int content_bufsize) 


Start sending the request. 


Parameters: 


+- ses session handle. 
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— tr transaction handle. 

— header_buf buffer for receiving header. 

— header_bufsize size of header_buf. 

— content_buf buffer for receiving content. 

— content_bufsize size of content_buf. 
Return values: 

HTTP_RC_SUCCESS success. 

negative-value error. reason code returned. 


Note: 


Do not call this function in callback function from HTTP-Lib. 


5.4.5.10 int NetHttpSetReqContent (NetHttpTrHandle tr, const void x content, int content_len) 


Set a request body. 


Parameters: 
< tr transaction handle. 
— content content. 
— content_len length of content. 
Return values: 
HTTP_RC_SUCCESS success. 
negative-value error. reason code returned. 
Note: 


Do not call this function in callback function from HTTP-Lib. 


5.4.5.11 int NetHttpSetReqContentChunk (NetHttpTrHandle tr, const void x content, int 
content_len, NetHttpFlag content_end) 


Set a request body in chunk sending. 


Parameters: 

— tr transaction handle. 

— content chunked request content. 

— content_len length of content. 

— content_end content termination flag. 
Return values: 

HTTP_RC_SUCCESS success. 

negative-value error. reason code returned. 
Note: 


This function is not supported in this revision, and return error. 
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5.4.5.12 int NetHttpStartSSL (NetHttpSesHandle ses, const char « hostname, int hostnamelen) 


Request SSL establishment. 


Parameters: 
< ses session handle. 
— hostname host name of http server. 


— hostname_len length of hostname. 


Return values: 


HTTP_RC_SUCCESS success. 


negative-value error. reason code returned. 


Note: 
Do not call this function in callback function from HTTP-Lib. 


5.4.5.13 int NetHttpStopSSL (NetHttpSesHandle ses) 


SSL termination request. 


Parameters: 


< ses session handle. 


Return values: 


HTTP_RC_SUCCESS success. 


negative-value error. reason code returned. 


Note: 


Do not call this function in callback function from HTTP-Lib. 
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